README for yMod v0.1
--------------------

This is a first release, so there will be bugs!

- What does this mod do?
It replaces the hardcoded maximum height of 128 by 256, 512 or 1024 (and 
possibly even bigger values but those I've not tested). Every maximum height 
value has 5 save directories of its own, so you don't accidentally use
a save with an incompatible height. Optionally, the terrain generated by Minecraft
is stretched up to get bigger mountains/hills/other stretched.

- What does this mod NOT do?
This mod does NOT convert old saves into the new format, but that's planned
for the next version!
Multiplayer will NOT work in this version. The Nether is untested but might work.
Then again, it might not! This mod also doesn't fundamentally change the way the
terrain is generated, so you won't get nice looking vast mountains, just terrain
scaled up into the air; be prepared for steep mountainsides! The stretching
can lead to very weird things like flooded worlds and impossible mountains, so
if you don't like it, turn it off and build your own mountains. 
 
- Installation instructions:
Put the .class files in the zipfile into minecraft.jar, and delete the META-INF
folder in the jar (as usual). Optionally, place scalePercentages.txt into the 
root of the .minecraft folder. See below for lots more info on what goes into
this file.

Start minecraft, singleplayer and you'll see an empty directory with the new
maximum height above it. 

IF YOU STOP READING HERE, YOU'LL GET A MINECRAFT WITH A NORMAL WORLD, BUT A
HEIGHT LIMIT OF 512. THE CLOUDS WILL BE GONE, BECAUSE THEY'RE TOO HIGH UP...

Read on for more details & tuning possibilities, however.

- Setting the maximum height via environment variable YLIMIT_EXTRA_BITS
Before starting the modded Minecraft, you can set the environment variable
YLIMIT_EXTRA_BITS (on Windows XP this can be done via My Computer -> Properties 
-> Advanced -> Environment Variables, I don't know how works for other OSes, 
sorry!). The value of this variable should be a single digit from 0 to 9, and it
controls how many times the old limit is multiplied by 2. Here's a table:
YLIMIT_EXTRA_BITS | maximum height
------------------+---------------
        0         |   128
        1         |   256
        2         |   512 (default)
        3         |   1024
        4         |   2048 (untested!)
        5         |   4096 (untested!)
        6         |   8192 (untested!)
        7         |   16384 (untested!)
        8         |   32768 (untested!)
        9         |   65536 (untested!)
If you don't set the value it defaults to 2, for a maximum height of 512. For 
netbooks I recommend the value 1, while those with powerful computers and lots
of patience can try 3. There's not much point in using 0 as that will not change
anything, except for changing the savefile format in an incompatible way.
        
- New savefile location and format
Instead of world save folders World1 to World5, each maximum height get it's own
5 save folders, called World_128_1 to World_128_5, World_256_1 to World_256_5
and so on. This is done to make sure you only load and save worlds with the right
height maximum. Be aware that this will confuse tools like InvEdit, so that you
might have to rename these folders back and forth manually in order to use these
tools. Map viewing and editing tools most likely will not work, since the save
file format is changed!   

- Stretching and the file scalePercentages.txt
In order to get some interesting to stuff to look at, I've implemented something
called stretching, which enlarges the output of minecraft's terrain generator.
Minecraft tends to generate a world full of dirt, stone and ores up to height 64,
after which hills, trees and air tend to take over until 128. This mod offers two
ways to make the generated world fill more of the new size: either the below-sea
level stuff is enlarged, or the above-sea part is. (Both at the same time is also
possible, but not in this version). Per 16x16 chunk you can give a number that
determines how the stretching happens: -100 means the below-sea is stretched as
far as it can while keeping the over-sea the same size, 0 means both stay the
same size and +100 means the below-sea stays the same, while the over-sea gets
stretched all the way. Numbers in between do something in between.

This sounds pretty complicated so here's an example. Let's say the maximum height
is 512. If you did nothing, you'd have 512-64 = 448 blocks above sealevel. The 
terrain coming from minecraft only goes up to (about) 128 so you'd have 384
levels of totally empty space. Fine for builders, not fine for people who want
bigger mountains. If we stretch the over-sea as far as it can go (which is by
a factor of 448/64 = 7) we get mountains which potentially can go to 512, but
every little bump becomes a 7-high wall. So if you scale 50% the factor is
midway between 1x (doing nothing) and 7x (all the way) for a factor of 4 - that
means the top of the generated blocks go to 64 + 64 * 4 = 320. (The first 64 is
for the unchanged under-sea). 25% would mean scaling by 2.5 and 75% is 5.5 and
so on.
Now, if you'd like the surface to stay more-or-less unchanged, you can also
apply this to the under-sea level blocks. This tends to give a deeper world,
where the surface is as normal, but the caves are bigger. (Note however, that
ore distribution does not change, diamonds will still be just near the bottom).

A few values in a table, showing the effect of varying stretch %-ages for
different maximum heights:    
Max | %-age| f| Sealevel | Surface | Top of world
----+------+--+----------+---------+-------------
256 | -100 | 3|   192    |  64     |  256
256 |  -50 | 2|   128    |  64     |  192
256 |    0 | 1|    64    |  64     |  128
256 |   50 | 2|    64    | 128     |  192
256 |  100 | 3|    64    | 192     |  256
----+------+--+----------+---------+-------------
512 | -100 | 7|   448    |  64     |  512
512 |  -50 | 4|   256    |  64     |  320
512 |    0 | 1|    64    |  64     |  128
512 |   50 | 4|    64    | 256     |  320 
512 |  100 | 7|    64    | 448     |  512
----+------+-+----------+---------+-------------
1024| -100 |15|   960    |  64     |  1024
1024|  -50 | 8|   512    |  64     |  576
1024|    0 | 1|    64    |  64     |  128
1024|   50 | 8|    64    | 512     |  576
1024|  100 |15|    64    | 960     |  1024


All this is controlled via a file scalePercentage.txt which should be in the
root of the .minecraft folder. Lines starting with # and blank lines are ignored
while lines containing numbers are interpreted as stretching percentages. To get
more varied terrain, you can give rectangular grids of numbers which are
smoothed a bit (to prevent super-steep walls) and applied repeating in the N-S
and E-W directions. But if you put just one number, that's always applied to
every chunk, and if the file is missing, nothing happens - no stretching is done.
Here's a couple of sample files:
This makes everything above sea level fill half the available space: 
#START
50
#END

This makes everything under sea level fill half the available space:
#START
-50
#END

This one makes most of the world act normally, except every 8 chunks (that's
128 blocks) where there's a huge mountain. Replacing -50 by +50 enlarges the
over-sea features so if there's a sea there, you won't see much.
#START
0 0 0   0   0 0 0 0
0 0 0   0   0 0 0 0
0 0 0   0   0 0 0 0
0 0 0 -50 -50 0 0 0
0 0 0 -50 -50 0 0 0
0 0 0   0   0 0 0 0
0 0 0   0   0 0 0 0
#END

This raises sea-level more or less uniformly, but there a canyon running
through the world every 5 chunks and a bit higher piece of the world once
every so often:
#START
-25 -25 -25 -30 -25
-25 -25 -25 -25 -25
-20 -20 -20 -20 -20
-25 -25 -25 -25 -25
-25 -25 -25 -25 -25
#END

Feel free to experiment, but be aware that this part of the mod will probably
change a lot in later versions...
I have tried a bit to prevent water getting too high up and flooding the rest
of the world, but I'm not 100% sure got it working perfectly. Be ready for
surprises!

- New savefile format
(this section is *very* technical and mainly of interest to tool makers).
I've made the following changes to the format: 
 * In the level.dat file, an extra Integer field called YLimit is added, with
    the maximum height (256/512/etc) as its value. This is mainly there so you
    know how big the arrays in the chunks are going to be.
  * In the per-chunk file, the following fields get enlarged by an appropriate
    amount: Blocks, Data, SkyLight and BlockLight. The format here stays the
    same, so you get a sequence of bytes/nibbles with fixed x and z, and y
    runs from 0 to the heightlimit in each. 
  * The field HeightMap is saved using a new NBT type, called NBTTagIntArray.
    It's code is 11, but otherwise it is analogous to the bytearray type (so
    first the length, and then the bytes, written out using Java's writeInt
    method).
If this is in anyway relevant to you, you might also be interested in the
patch diff (also in the zipfile and called ylimit.patch), there you can find the
gory details.     